﻿//_______________________________________________________________________________________________________________________
// Copy Right (c) 2010, 2011 SapiensIT Consulting GmbH, all rights reserved
//_______________________________________________________________________________________________________________________
// THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT
// NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
//_______________________________________________________________________________________________________________________
// PROJECT:     sapiens.at.SharePoint (SharePoint 2010/V4)
//_______________________________________________________________________________________________________________________
// VERSION:     2.0
//_______________________________________________________________________________________________________________________
// DESCRIPTION: 
//_______________________________________________________________________________________________________________________
// LICENSE:     Different licens Types apply to different file types:
//               - Source code files are governed by the MICROSOFT PUBLIC LICENSE (Ms-PL)
//               - Binary files are governed by MSDN CODE GALLERY BINARY LICENSE
//               - Documentation files are governed by CREATIVE COMMONS ATTRIBUTION 3.0 LICENSE
//
//               The licenses can be found at the projects source location.
//               If you do not agree, don't use it!
// 
//_______________________________________________________________________________________________________________________
// Start SharePoint Branding, visit http://www.cliggin.com! Visit us on http://www.sapiens.at! Tell your friends! 
//_______________________________________________________________________________________________________________________
using System;
using System.Collections.Generic;
using Microsoft.SharePoint;
using Sapiens.at.SharePoint.Entities;
namespace Sapiens.at.SharePoint.Repositories
{
    /// <summary>
    /// Interface for list repositories. See <see cref="ListRepository"/> for a standard implementation.
    /// </summary>
    /// <seealso cref="ListRepository"/>
    public interface IListRepository
    {
        /// <summary>
        /// Creates a new ListItem for this list and returns it as an Entity. NOTE: The ListItem is not yet saved. Use <see cref="IEntity.Update()"/>
        /// or <see cref="IEntity.SystemUpdate()"/> to do so.
        /// </summary>
        /// <remarks>
        /// The method tries to get the <see cref="SPContentTypeId"/> from the <typeparamref name="TEntity"/> using the static field 'CTypeId'.
        /// If this field is not available it throws a TargetException. Implement the field using
        ///     <code>public static readonly SPContentTypeId CTypeId = new SPContentTypeId(CTYPE_ID);</code>
        /// or use another overriden method of <see cref="Create{TEntity}()"/> instead.
        /// </remarks>
        /// <typeparam name="TEntity">The entity type to return</typeparam>
        /// <returns>A new ListItem with the contenttype specified in the proper Entity class</returns>
        TEntity Create<TEntity>() where TEntity : IEntity;

        /// <summary>
        /// Creates a new ListItem for this list and returns it as an Entity. NOTE: The ListItem is not yet saved. Use <see cref="IEntity.Update()"/>
        /// or <see cref="IEntity.SystemUpdate()"/> to do so.
        /// </summary>
        /// <typeparam name="TEntity">The entity type to return</typeparam>
        /// <param name="cTypeId">The contenttype to assign to the new listitem</param>
        /// <returns>A new ListItem with the specified contenttype</returns>
        TEntity Create<TEntity>(SPContentTypeId cTypeId) where TEntity : IEntity;

        /// <summary>
        /// Creates a new ListItem for this list and returns it as an Entity. NOTE: The ListItem is not yet saved. Use <see cref="IEntity.Update()"/>
        /// or <see cref="IEntity.SystemUpdate()"/> to do so.
        /// </summary>
        /// <typeparam name="TEntity">The entity type to return</typeparam>
        /// <param name="cTypeId">The contenttype to assign to the new listitem</param>
        /// <param name="parent">If not null, the new listitem is created inside the folder of this listitem</param>
        /// <param name="objectType">The object type this listitem represents</param>
        /// <returns>A new ListItem with the specified contenttype</returns>
        TEntity Create<TEntity>(SPContentTypeId cTypeId, SPListItem parent, SPFileSystemObjectType objectType) where TEntity : IEntity;

        /// <summary>
        /// Creates a new ListItem for this list and returns it as an Entity. NOTE: The ListItem is not yet saved. Use <see cref="IEntity.Update()"/>
        /// or <see cref="IEntity.SystemUpdate()"/> to do so.
        /// </summary>
        /// <typeparam name="TEntity">The entity type to return</typeparam>
        /// <param name="cTypeId">The contenttype to assign to the new listitem</param>
        /// <param name="parent">If not null, the new listitem is created inside the folder of this listitem</param>
        /// <param name="objectType">The object type this listitem represents</param>
        /// <param name="FileLeafRef">The Name of the new entity</param>
        /// <returns>A new ListItem with the specified contenttype</returns>
        TEntity Create<TEntity>(SPContentTypeId cTypeId, SPListItem parent, SPFileSystemObjectType objectType, string FileLeafRef) where TEntity : IEntity;

        /// <summary>
        /// Gets all entities from the repository.
        /// </summary>
        /// <remarks>
        /// Uses the search scope "RecursiveAll".
        /// </remarks>
        /// <typeparam name="TEntity"></typeparam>
        /// <returns></returns>
        IEnumerable<TEntity> GetEntities<TEntity>();

        /// <summary>
        /// Gets all entities from the repository from a certain content type.
        /// </summary>
        /// <typeparam name="TEntity"></typeparam>
        /// <param name="cTypeId"></param>
        /// <returns></returns>
        IEnumerable<TEntity> GetEntities<TEntity>(SPContentTypeId cTypeId);
        
        /// <summary>
        /// Gets all entities from the repository matching the query.
        /// </summary>
        /// <typeparam name="TEntity"></typeparam>
        /// <param name="query"></param>
        /// <returns></returns>
        IEnumerable<TEntity> GetEntities<TEntity>(SPQuery query);

        /// <summary>
        /// Gets all entities from the repository using a search scope.
        /// </summary>
        /// <remarks>
        /// The scope can be "Recursive", "RecursiveAll"
        /// </remarks>
        /// <typeparam name="TEntity"></typeparam>
        /// <param name="scope"></param>
        /// <returns></returns>
        IEnumerable<TEntity> GetEntities<TEntity>(SPViewScope scope);

        /// <summary>
        /// Finds an entity from the repository with its id.
        /// </summary>
        /// <typeparam name="TEntity"></typeparam>
        /// <param name="id"></param>
        /// <returns></returns>
        TEntity GetEntity<TEntity>(int id) where TEntity : IEntity;
        
        /// <summary>
        /// Gets the SPList that this Repository wraps
        /// </summary>
        SPList List { get; }

        /// <summary>
        /// Gets the SPWeb that this list is in
        /// </summary>
        SPWeb Web { get; }
    }
}
